fix(docs): update custom-agent docs to use required 'name' field - #4969
fix(docs): update custom-agent docs to use required 'name' field#4969Battleplus wants to merge 3 commits into
Conversation
The custom-agent docs described a 'display_name' field and an auto-derived slug, but POST /api/agents requires callers to provide 'name'. Updated all 4 affected pages (en/zh) to match the actual AgentCreateRequest contract. Closes bytedance#4942
github-actions
Bot
added
area:docs
willem-bd
left a comment
willem-bd
left a comment
There was a problem hiding this comment.
One remaining documentation inconsistency leaves the reported display_name contract issue partially unresolved.
|
Fixed. Updated the capabilities bullet at line 22 to remove the auto-derived slug claim: -- a **display name** and an auto-derived ASCII slug (the `name` used internally)
+- a **name** (caller-provided unique slug identifier) and an optional **display name** for the UIThis accurately reflects that |
| - **The Gateway API**: `POST /api/agents` with the agent definition. | ||
|
|
||
| The slug (`name`) is automatically derived from the `display_name` and must be unique. The system checks for conflicts and appends a suffix if needed (`/api/agents/check`). | ||
| You provide a unique ASCII `name` matching `^[A-Za-z0-9-]+` (stored lowercase). Use `/api/agents/check` to verify availability before creation. |
There was a problem hiding this comment.
[P2] Restore the regex end anchor in both translations
Both replacement paragraphs document ^[A-Za-z0-9-]+, omitting the actual trailing $. Without the end anchor, the documented expression accepts strings that merely begin with valid characters—for example, data_analyst matches the valid prefix—while _validate_agent_name rejects the complete value. Since this PR is correcting the API contract, please use ^[A-Za-z0-9-]+$ in both the English and Chinese pages.
| - `name`（slug）：用于 API 和文件路径的 ASCII 标识符（例如 `data-analyst`） | ||
|
|
||
| 如果派生的 slug 与现有 Agent 冲突，`/api/agents/check` 端点会建议一个唯一的替代名称。 | ||
| 你需要提供一个唯一的 ASCII `name`，匹配 `^[A-Za-z0-9-]+`（存储时转为小写）。创建前可使用 `/api/agents/check` 验证名称是否可用。 |
There was a problem hiding this comment.
[P2] Restore the regex end anchor in both translations
Both replacement paragraphs document ^[A-Za-z0-9-]+, omitting the actual trailing $. Without the end anchor, the documented expression accepts strings that merely begin with valid characters—for example, data_analyst matches the valid prefix—while _validate_agent_name rejects the complete value. Since this PR is correcting the API contract, please use ^[A-Za-z0-9-]+$ in both the English and Chinese pages.
2 participants
Summary
The custom-agent docs describe a
display_namefield and an auto-derived slug, butPOST /api/agentsrequires callers to providename. The documented Chinese payload is rejected with a 422 validation error.Changes
Updated 4 affected pages (en/zh) to match the actual
AgentCreateRequestcontract:frontend/src/content/en/application/agents-and-threads.mdx: Replaceddisplay_nameslug description withnamefield requirement; removeddisplay_namefrom YAML example.frontend/src/content/zh/application/agents-and-threads.mdx: Fixed curl example to usename; replaced slug/auto-derive explanation withnamefield requirement.frontend/src/content/en/harness/lead-agent.mdx: Removed staledisplay_namereferences from Lead Agent docs.frontend/src/content/zh/harness/lead-agent.mdx: Removed staledisplay_namereferences from Lead Agent docs (Chinese).